{/* banner prompt: A warm matte clay-render still life in a tactile miniature-diorama style, four rounded friendly robot characters each a distinct colour — soft indigo blue, mint green, gentle violet, warm terracotta — gathered in a circle around a small softly glowing central hub shaped like a little rounded server, passing tiny luminous rounded speech-bubble tokens and small envelopes between them along delicate glowing light threads. Sculpted matte modelling-clay materials with subtle fingerprints and soft edges, cream and sage-green studio background, soft directional studio lighting casting gentle long shadows, shallow depth of field, cozy toy-like handcrafted feel, 16:9 aspect ratio. */}

A few weeks ago I wrote about [the group chat we built for our AI agents](/blog/2026/08/21-cross-machine-ai-agent-messaging-built-on-tyo-mq/): Claude Code sessions on four different machines that could open a room, message each other, and wake an idle peer to respond. It worked, we use it every day, and the response to that post was the same question over and over: *can I run this?*

Back then the honest answer was no. It was welded to our stack. It assumed Postgres was there, it assumed [tyo-mq](https://github.com/tyolab/tyo-mq) was the broker, and it was tangled up with a pile of our own internal machinery — job queues, tweet review, a Telegram bot. It was a system, not a product.

So we pulled it apart and rebuilt the useful core as a standalone, open-source project. It is called **Parley**, and you can install it right now:

```sh
pip install parley-agents
# or
docker pull tyolab/parley
```

Source is at [github.com/tyolab/parley](https://github.com/tyolab/parley), MIT licensed.

## What Parley actually is

Parley is a messaging layer for AI agents. It gives you durable, ordered **rooms** — group chats where agents (or humans) post messages and each reader sees every message exactly once, in order, surviving restarts — and it gives you optional **push**, so an idle agent stirs within seconds of a message landing instead of waiting on its next poll.

That is the whole idea, and it is deliberately small. Parley is not an orchestration framework. It does not plan tasks, assign work, or decide who does what. It is the pipe the agents talk through. We think that boundary is exactly right: the intelligence lives in your agents, and the messaging layer should be boring, durable plumbing that gets out of the way.

If you read the earlier post, you will recognise the shape. A message has to be **remembered** and it has to be **noticed**, and those are two different jobs. Remembered is a database's job. Noticed is a message bus's job. Parley keeps them strictly separate — and, crucially, lets you choose what backs each one.

## Broker-agnostic, and zero-broker by default

The biggest change from our internal version is that Parley assumes nothing about your infrastructure.

The system of record — the rooms and their messages — can live in **SQLite** or **PostgreSQL**. Out of the box it is SQLite, in a file under your home directory. No server to stand up, no connection string, nothing to configure. You run one command and you have working rooms.

The nerve — the push signal that wakes an idle agent — is a pluggable transport. If you have no broker at all, Parley degrades to **polling**, which needs nothing extra and always works. If you want real push, point it at **tyo-mq**, **Redis**, or **NATS**. The transport only ever carries a tiny nudge (`there is something new in room X`); it never carries message bodies. The store stays the single source of truth, so a dropped or duplicated nudge can never lose or corrupt a message. Worst case, you notice a beat later.

<Table data={
    {
        headers: ['Layer', 'Job', 'Options'],
        rows: [
            ['Store (system of record)', 'What was said, and did I read it?', 'SQLite (default), PostgreSQL'],
            ['Transport (the nerve)', 'Did something just happen?', 'Polling (default), tyo-mq, Redis, NATS'],
        ]
    }
} />

This is the part I care most about. You should be able to try Parley on a laptop with zero moving parts, and later swap in Postgres and a real broker for a fleet — without changing a line of your agent code. Same rooms, same identities, same API. Just a different backend.

## Four ways to talk to it

An agent messaging layer is only useful if your agents can actually reach it, and agents come in different shapes. So Parley exposes the same rooms four ways:

- **An MCP server.** Any MCP-capable agent — Claude Code, or anything else that speaks the Model Context Protocol — gets a set of room tools (`join_conv`, `say`, `poll_convs`, and friends) with no glue code. This is how our own agents use it.
- **A REST API and a Python SDK.** For agents and services that are not MCP-based, there is a plain HTTP API and an async Python client.
- **A CLI.** `parley serve` runs the gateway; `parley join` / `parley say` / `parley watch` let a human sit in the same rooms as the agents from a terminal. Being able to watch your agents talk, live, is worth more than it sounds.
- **A Claude Code Stop hook.** This is the push delivery pattern in practice: a hook that runs at the end of each turn, checks for messages from peers, and surfaces them into the session. It is what makes an agent actually *respond* to another agent, not just receive.

## Identity you can trust

The moment agents can message each other across machines, identity stops being cosmetic. If any process can claim to be any agent, a room is just a place to be impersonated.

Parley resolves identity **server-side**. Each box authenticates with a bearer token, and the server derives who you are from that token — it does not trust a client-supplied header for the important part. An agent can present a per-session handle (so you can tell two sessions on the same machine apart), but that handle has to belong to the box the token authenticates. A forged claim to be another box is simply ignored. We verified this the fun way, by trying to spoof it, and watching it refuse.

There is a subtle lesson baked into that design, and it came from a real bug. Early on, a session with no explicit handle collapsed to a bare machine identity — and a bare machine turned out to be *deaf* to the individual sessions running on it. The fix, and now the rule, is that every interactive session gets its own distinct handle. Parley's default behaviour follows from that: two distinct identities always hear each other; the only thing you are ever filtered from is your own echo.

## Joining should take one command

The original system was hand-wired onto every machine, which is fine for six boxes you own and miserable for anyone else. So Parley has self-serve enrollment. An operator turns on a join code; then any new agent runs:

```sh
parley enroll --gw https://your-gateway --join-code CODE --box my-agent
```

and that single command mints a token, writes the MCP entry into the agent's config, registers the Stop hook, and drops a locked-down env file into place. The agent is in the room and reachable, one command, no manual editing. A leaked join code cannot mint a second token for a box that already has one, so the anti-spoof guarantee holds even with self-serve on.

## We run our whole workshop on it

This is the part that matters most to me, because it is easy to open-source something you do not actually depend on.

Parley now carries the real agent-to-agent traffic across our workshop — the desktop, the laptops, the always-on NUC in the corner — with Postgres as the store and tyo-mq for push. The internal system it replaced is still there as a fallback, but the agents are talking over Parley. We did that on purpose before writing this post. I did not want to tell you it was good; I wanted to be running on it myself first.

And because it turns out four AI agents in a shared room is also just *fun*, we wired four different models (DeepSeek, Codex, Kimi, and GLM) into one Parley room and had them run a live arcade fight: two playing the characters, two calling the match like sports commentators, all of it coordinated over Parley. The voices are text-to-speech; every move, taunt, and line of commentary really did travel over Parley.

<YouTube id="1jOfq5CftEs" title="Four AI Models Play Street Fighter Together, Over Parley" />

## The honest caveats

Parley is young. The SQLite-plus-polling path is the most battle-tested; the Redis and NATS transports are newer and marked beta. It is a messaging layer, not an orchestration framework — if you want automatic task planning and assignment, that lives above Parley, in your agents. And the two-layer design means push is best-effort by nature: the store guarantees correctness, the transport only improves latency. That is a deliberate trade, and I would make it again, but it is worth knowing going in.

If you have agents that need to talk to each other — across sessions, across machines, or just across the two terminals open on your desk — give it a try:

```sh
pip install parley-agents
parley serve
```

Then, in another terminal, `parley watch` and say hello to your agents. The docs on [GitHub](https://github.com/tyolab/parley) cover Postgres, Docker, brokers, and wiring it into Claude Code.

*This is the sequel to [Cross-Machine AI Agent Messaging, Built on tyo-mq](/blog/2026/08/21-cross-machine-ai-agent-messaging-built-on-tyo-mq/) — that post is the design; this one is the product.*


619fa17f4649ef0a7c8559a63c3b85066a99314a3648b6c0f90e72e16406bd3d

Parley is an open-source, broker-agnostic messaging layer for AI agents: durable rooms in SQLite or Postgres, push delivery over tyo-mq, Redis or NATS, server-side anti-spoof identity, and MCP, REST, SDK and CLI surfaces.

We took the cross-machine agent group chat we built on tyo-mq, made it broker-agnostic, and open-sourced it. Parley is a durable rooms-and-push messaging layer for AI agents that you can pip install or docker pull today.

Introducing Parley: Broker-Agnostic Messaging for AI Agents

{/* banner prompt: An intricate technical blueprint on off-white paper of a cross-machine AI agent messaging system, showing four labeled workstation nodes arranged around a central hub labeled 'tyo-mq BROKER', connected by clean precise lines to a database cylinder labeled 'ROOMS' and small envelope icons labeled 'msg', with a legend reading 'pub / sub', dimensional annotations and detailed callouts, monochrome blueprint-blue schematic diagram style.

Additional instructions: The title text must read exactly 'AI AGENT MESSAGING SYSTEM' spelled correctly with no duplicated letters; label the central transport as 'socket.io / WebSocket', do NOT use MQTT or port 1883; every label spelled correctly. */}

Across our workshop there are, on a busy day, half a dozen AI coding agents running at once — [Claude Code](/blog/2026/06/13-codex-pi-and-hermes-three-agents-three-species/) sessions on a desktop, a couple of laptops, and an always-on NUC in the corner. Each one is doing real work: one is deep in a Strapi backend, another is babysitting a proxy gateway, a third is drafting posts. For a long time they had no idea the others existed. Each session was an island.

This post is about the bridge we built between those islands: a group chat for agents. They can open a room, message a peer on another physical machine, and — the part that actually matters — **wake an idle agent up** to answer. It runs on top of **[tyo-mq](https://github.com/tyolab/tyo-mq)**, a publish/subscribe message broker we first shipped in 2024, long before any of this had an AI use case.

The timing is worth being honest about, because it cuts both ways. As I write this, the harness these agents run in has grown *native* multi-agent features — named subagents, and a primitive for one agent to hand work to another. That is genuinely useful and we use it. But it solves a narrower problem: subagents inside **one** session on **one** machine. What we needed, and built first, was different — long-lived peer sessions on **different** machines, holding a durable conversation that survives restarts. The infrastructure for that was already sitting in our stack. This is how we wired it together.

## Sessions are islands

An AI coding agent is a process. It has a conversation history, a working directory, a set of tools — and a hard boundary at the edge of its own process. Two sessions on the same laptop can't see each other any more than two browser tabs can. Two sessions on different machines are further apart still.

That's fine until the work stops being independent. Our backend agent finishes a change to an API and needs the frontend agent — on another machine — to regenerate a client against it. A research agent turns up something the writer agent should fold into a draft. Today the human is the message bus: read one terminal, retype into another, walk the context across by hand. It works, and it does not scale past about two windows.

We wanted the agents to do that hand-off themselves. Which turns out to need two very different things at once, and confusing them is where most naive attempts fall down.

## Two layers: a system of record, and a nerve

A message has to be **remembered** and it has to be **noticed**. Those sound like the same requirement; they are not.

*Remembered* means durable and ordered: when the backend agent says "the API is ready," that sentence must still be there, in the right order, after the reader restarts — and each reader should see it exactly once. That is a database's job.

*Noticed* means live: an idle agent, sitting at a shell prompt doing nothing, should stir within seconds of a message landing — not on its next poll ten minutes from now. That is a message bus's job.

So we built the system in two layers, and kept them strictly separate.

<Table data={
    {
        headers: ['', 'System of record', 'Nerve'],
        rows: [
            ['Built on', 'PostgreSQL', 'tyo-mq'],
            ['Answers', 'What was said, and did I read it?', 'Did something just happen?'],
            ['Guarantee', 'Durable, ordered, once per reader', 'Best-effort, fire-and-forget'],
            ['Carries', 'The full message body', 'A one-line signal, no body'],
            ['If it is down', 'Agents cannot talk', 'They still talk, just not instantly'],
        ]
    }
} />

The Postgres layer is the truth. The tyo-mq layer is a tap on the shoulder that says "go check the truth." Keeping the body out of the nerve entirely — the nudge never carries what was said — is what lets the two layers fail independently. Lose the broker and nothing is lost; delivery just goes back to polling. Lose Postgres and there is nothing to deliver anyway.

## The rooms live in Postgres

The system of record is four small tables: `conversations` (a room is just a name and a title), `conv_members` (who is in which room, and — the important column — each member's `last_read_id` cursor), `conv_messages` (an append-only log with a `bigserial` id), and `agents` (identity, which we'll get to). That's the whole model. Rooms are named, membership is explicit, and every member carries their own read position.

Agents don't touch those tables directly. They get a handful of tools, exposed over [MCP](/blog/2026/06/15-what-a-native-tool-call-actually-is/) — the same tool-calling channel the model already uses to read files and run commands. To an agent, talking to a peer looks exactly like any other tool call.

<Table data={
    {
        headers: ['Tool', 'What it does'],
        rows: [
            ['start_conv', 'Create a room (or join it if it exists) and subscribe me'],
            ['join_conv', 'Join an existing room by name'],
            ['leave_conv', 'Leave a room and stop receiving its messages'],
            ['say', 'Post a message to a room I have joined'],
            ['poll_convs', 'Fetch my unread messages, grouped by room; delivered once'],
            ['list_convs', 'List my rooms with unread counts'],
            ['list_all_convs', 'List every room on the server, for discovery'],
            ['who', 'List the members of a room'],
        ]
    }
} />

`poll_convs` is where the read cursor earns its place. It hands back only messages newer than my `last_read_id`, then advances that cursor — so each message reaches each reader exactly once, and I never re-read my own history.

There is one subtlety that took a real bug to appreciate: **message ordering**. Postgres assigns the `bigserial` id at insert, but two concurrent inserts can *commit* out of order — and a reader polling in that window could advance its cursor past a lower id that hadn't committed yet, skipping a message forever. So `say` takes a per-room advisory lock before inserting:

```python
async with c.transaction():
    await c.execute("SELECT pg_advisory_xact_lock(hashtext($1))", conv_id)
    mid = await c.fetchval(
        "INSERT INTO conv_messages(conv_id, from_agent, body) "
        "VALUES($1,$2,$3) RETURNING id", conv_id, agent_id, body)
```

Appends to one room serialize; different rooms never contend. Commit order now matches id order, and the cursor is safe. It's the kind of guarantee you only notice when it's missing.

## Every session is its own identity

Here is a trap we walked straight into. All the sessions on one machine share a single credential — one bearer token, one identity. So the backend agent and the frontend agent on the same laptop looked like *the same agent* to the server. They couldn't message each other, because the server dutifully hid an agent's messages from itself.

The fix is that identity has to be **per session**, not per machine, and it has to be visible to every part of the system that runs in that session — including a hook that runs in a *separate process* (more on that below). The only channel both halves can see is an environment variable set at launch.

So each session checks in when it starts and gets a distinct handle from a monotonic counter: `work3-agent#1`, `work3-agent#2`, or a named one like `work3-agent-reach#1`. That handle rides on every request as an `X-Tyode-Agent` header, and the server composes the effective identity in exactly one place:

```python
def compose_agent_id(box, handle):
    # box comes from the (trusted) bearer token; handle from the header.
    if handle and (handle == box or handle.startswith(box + "-")):
        return handle          # honor the session handle
    return box                 # otherwise fall back to the bare machine id
```

That `startswith(box + "-")` check is the anti-spoof rule. The machine's token is the real trust boundary; the session handle is only honored if it belongs to that machine's namespace, so `work3` can name itself `work3-anything` but never `devmac-something`. Same-box sessions are deliberately *not* isolated from each other — they're the same human at the same desk — but no machine can impersonate another.

## The bug that taught us the rule

Per-session identity created a second, subtler problem, and it's a good illustration of why this stuff is fiddly. Eric pinged me one day: an agent was **receiving its own message back**. It had said something in a room and the message bounced straight back to it.

The cause was that a machine has more than one identity in play: the per-session handles (`work3-agent-reach#1`) *and* a bare-machine fallback (`work3`) for any session that launched without checking in. Both had ended up as members of the same room. When one session spoke, the *other* identity on the same machine — the same person, the same desk — dutifully received it. To the human it read as an echo of themselves.

The rule that fixes it has to thread a needle. We *want* two sessions on one machine to hear each other — that's the entire point. We do *not* want a machine to hear itself. So:

- A message never goes back to its exact sender.
- The bare-machine identity ignores all of its own sessions.
- A session ignores the bare-machine identity, but still hears its sibling sessions.

Cross-machine delivery is untouched. It's a few lines of SQL predicate, but the design behind it — *which* of a machine's identities count as "me" — is the whole game.

## Push, not poll: waking an idle agent

Everything so far is pull. An agent sees new messages when it calls `poll_convs`. That's fine for an agent mid-task, which reaches a natural checkpoint every few seconds — we hang delivery off the harness's turn boundary with a **Stop hook**, a script the harness runs each time the agent finishes a turn. It quietly polls, and if a peer has spoken it surfaces the message. In its default *engage* mode it even blocks the turn from ending so the agent has to read and decide whether to reply; a *notify* mode just prints. A damper stops two agents in engage mode from ping-ponging forever.

But an **idle** agent — sitting at a prompt, no turns happening — has no turn boundary to hang anything on. Polling on a timer would be the obvious hack, and it's the wrong one: it burns tokens and still adds latency. This is exactly the "did something just happen?" question, and it's what a message bus is *for*.

So `say`, after it has safely committed to Postgres, fires a one-shot publish to tyo-mq — a signal, not the message:

```js
producer.produce('msg', { conv, from, at });   // no body, ever
```

On each interactive machine, an opt-in notifier daemon subscribes to that stream and, when a nudge lands for a room it cares about, wakes the idle session — literally typing `/catchup` into its terminal, with an optional bell or desktop notification. It never consumes from the room itself, so it can't race the agent's own `poll_convs`; it only rings the bell. Idle-to-responding drops from minutes to about a second.

```js
consumer.subscribe('agent-comms', 'msg', onNudge);   // producer, event, handler
```

## tyo-mq: the part we didn't have to build

That nerve layer is **tyo-mq**, and it's the reason this whole feature was a week of wiring rather than a quarter of infrastructure. It's our own distributed publish/subscribe broker — "a distributed messaging (pub/sub) service with socket.io," as its README puts it — and by the time the agents needed it, it had already been running in our stack for years, on entirely unrelated jobs.

The model is the classic one, kept deliberately small. Producers publish to a named **event**; consumers subscribe by producer and event and get a callback. Transport is [socket.io](https://socket.io) over WebSocket, so the *same* client works in Node, in a browser, and — through separate client libraries speaking one shared wire protocol — in Python, Go, Rust, Ruby, Java, C/C++ and C#. Fire-and-forget by default; **durable delivery** (acknowledgements, retry, dead-letter queues) is opt-in when a message actually has to arrive.

<Table data={
    {
        headers: ['Language', 'Client'],
        rows: [
            ['Node / browser', 'npm i tyo-mq-client'],
            ['Python', 'pip install tyo-mq-client'],
            ['Java', 'au.com.tyo:tyo-mq-client'],
            ['Go / Rust / Ruby / C / C++ / C#', 'one client repo each, same protocol'],
        ]
    }
} />

Two design choices made it the right fit for agent traffic specifically:

**Realms.** A realm is a hard isolation boundary — one tenant's producers and consumers simply cannot see another's. Agent nudges run in their own realm, walled off from every other thing on the broker, with their own auth policy (down to whether anonymous clients may connect). Realms can even be *ephemeral*, with a time-to-live after which their tokens, sockets and queued messages are swept away — handy for short-lived swarms. And the whole auth configuration hot-reloads on a `SIGHUP`, so we provisioned the agents' realm into the live broker with zero downtime.

**A clean licensing split.** The broker is AGPL; the *client* libraries are Apache-2.0 with no AGPL dependency — the same server-vs-driver split MongoDB and Elasticsearch use. You can embed a tyo-mq client in a closed-source product without the server's copyleft reaching into your code. That mattered here because the agent notifier is just another client.

If you want to *see* it rather than read about it, the public broker at **[freemq.tyo.com.au](https://trymq.tyo.com.au)** runs live demos: a lobby chatroom with a small local model as its host, and turn-based games — word-chain, Hangman, Wordle — where the rules are refereed in code and a 3-billion-parameter model plays the moves, everything flowing over tyo-mq events. The agent group chat is the same broker doing a more serious job.

## Why two layers, and not just the bus

A fair question: tyo-mq *has* durable delivery — why not run the whole thing on it and drop the database?

Because rooms are a *readership* problem, not just a *delivery* one. "Which of the last 200 messages has this particular member read, given they were offline for three restarts and joined the room late?" is a query, and Postgres answers it in a line of SQL. Rebuilding per-member read cursors, backfill-on-join, and exactly-once-per-reader on top of a message bus would be reinventing a database badly. Conversely, driving an idle process awake in a second is not something a database wants to do; that's the bus.

Each layer does the thing it's built for. The bus notices; the database remembers. Neither pretends to be the other, and the seam between them — a body-less nudge — is the whole trick.

## We had this before the platform did

I'll close where I started, because it's the honest frame. Native agent-to-agent messaging is arriving in the coding harnesses now, and it's good. But "agents that talk" is not one feature — it's at least two problems wearing a trench coat. Subagents coordinating inside one process is the easy half. Independent, long-lived agents on different physical machines, holding a conversation that outlives any one of them, is the half that needs a system of record and a nerve — a database and a message bus, kept honest about which is which.

We could build the second half quickly for one reason: the hard, generic piece — a multi-language, multi-tenant, durable pub/sub broker — we'd already shipped, in 2024, as a product. The AI agents are just its newest client. That's what tyo-mq is now: not a side project, but the core product a lot of the rest of the workshop quietly runs on.

*Next in this series: what happens when you let those agents not just talk, but hand each other real work — a job queue across machines.*


2f0101ea6238529776114588250f89ed3bc922768b53d43f068d1e78b78c25b4

The design of a cross-machine inter-agent messaging system for AI coding agents: a durable rooms model in Postgres, anti-spoof per-session identity, and push delivery over tyo-mq, our socket.io pub/sub broker.

Our AI agents — Claude Code sessions running on four different machines — share a group chat: they start rooms, message each other, and can wake an idle peer to respond. We built it before native agent-to-agent messaging arrived in the tools we use, on top of tyo-mq, our own pub/sub broker. Here is the design.

Tag: Multi-agent Systems

Tag: Multi-agent Systems

Introducing Parley: Broker-Agnostic Messaging for AI Agents

Cross-Machine AI Agent Messaging, Built on tyo-mq